<html>
<head>
  <title>OpenSocial Container Sample</title>
</head>

<body>
  <h1>OpenSocial Container Sample - Getting started</h1>

  <ul>
    <li><a href="#Purpose">Purpose</a>
    <li><a href="#Theory">Theory</a>
    <li><a href="#Practical">Practical</a>
    <li><a href="#Tips">Tips</a>
    <li><a href="#Redistribution">Redistribution</a>
    <li><a href="#Compatability">Compatability</a>
  </ul>

  <h2 id="Purpose">Purpose</h2>
  This sample serves two primary purposes:
  <ol>
    <li>To demonstrate how a container can be implemented using a simple
      example.
    <li>To create an environment for easy gadget testing. OpenSocial is all
      about social APIs, which means that gadget testing usually involves
      multiple user accounts. This container makes testing easy by letting
      gadgets specify arbitrary state for any number of users.
  </ol>

  <h2 id="Theory">How it works? (Theory)</h2>
  As the gadget developer you need to specify two pieces of information:
  <ol type="a">
    <li>URL to the gadget definition; and</li>
    <li>initial state of the container in the form of a URL to a state file.</li>
  </ol>

  You can find the DTD for the state definition in the docs/state.dtd folder.

  The state definition file allows you to specify the viewer of the gadget,
  the owner, the friends and the activities of those users. Once the gadget and
  its state are loaded you can use the gadget in the same way as any other
  container. At any point you can also dump a snap shot of the state of the
  environment to an XML file (with the same format as the state definition
  file).

  <h2 id="Practical">Trying out the test container (Practical)</h2>
  A sample gadget and state definition file have been provided with the package
  for your convenience. You can use them as follows:
  <ol>
    <li>Open the file samplecontainer.html with your browser.
    <li>The Gadget Location field should already be set to
      "examples/listfriends.xml". Click the button "Add Gadget".
    <li>The Container State field should already be set to
      "examples/state-listfriends.xml". Click the button "Set State".
    <li>Refresh the browser page (usually by pressing F5). Note: this is
      necessary because of a jquery bug and only needs to be done once.
    <li>You should see a list of friends. These friends were specified in the
      file examples/state-listfriends.xml
  </ol>

  Similarly you can also try out the sample "examples/clickme.xml" and
  "examples/state-clickme.xml".

  <h2 id="Tips">Tips/caveats</h2>
  <ul>
    <li>iGoogle-specific functions like <code>_gel</code> will not work.
    Use generic alternatives like <code>document.getElementById</code> instead.
    <li>Due to browser security restrictions, your gadget definition
      file and system state file must be on the same server as the
      container. The above step by step procedure runs the test container from the local
      file system. You can also copy the files to a web server and run off it
      instead.
    <li>The gadget definition URL and system state URL are stored in a cookie.
      You can set the values to empty or clear your cookies to clear existing
      values for those fields.
    <li>For easier debugging of your gadget script in Firebug, include the
      gadget script using a script tag in the gadget definition file, instead
      of inlining the script. Sometimes Firebug still cannot display the gadget
      javascript if it is on the local file system. To avoid this, you can untar
      the package to a web server and access it through an <code>http</code> URL
      to that server.
    <li>You always need to specify a state file for the container. At a minimum
      it must include the viewer name. All other fields are optional.
  </ul>

  <h2 id="Redistribution">Redistribution</h2>
  A copy of OpensocialReference.js and jquery.js have been included in this
  distribution for your convenience. For production systems, please use
  jquery.js from the site http://www.jquery.com and OpensocialReference.js from
  Google's official distribution.

  <h2 id="Compatability">Compatability</h2>
  This package has been tested on IE 6.0 on Windows and Firefox 2.0 on Linux and Windows.
  In theory it should work on other browsers and platforms, but this has not
  been tested.

</body>
</html>
